Teardown is a feature

Creating an environment is the part everyone demos. You push, a log scrolls, a link appears. Deleting it is the part that decides whether the system is still usable in a year. Every team I have seen build previews in-house got the first half working in a month and then spent the next twelve cleaning up after it.

We treat teardown as a feature with its own guarantees, its own log and its own number. The number is a median of 2m 12s from merge to the last resource removed.

The environment that outlives its branch

A preview that is still around after its pull request merges is worse than no preview. It costs money, obviously. But the real cost is that it is wrong. It shows code that is no longer the branch and not quite main, on data that is a week old, at a URL somebody bookmarked. Sooner or later someone files a bug against it.

Leftovers also pile up in places nobody looks. The pattern in home-built systems is always the same: containers get deleted because they show up on the bill, and everything else stays.

What teardown removes

When a preview is torn down, the runner removes all of the following and records each step.

• Containers for every service, after a graceful stop.
• Volumes, including the seeded database. There is no "keep the data just in case."
• DNS records and the certificate for the preview's hostname. The link returns a plain page saying the pull request merged, and when.
• Secrets scoped to the branch. Test keys issued for the preview are revoked, not just forgotten.
• Snapshot copies. The preview's restored copy of the masked snapshot goes with its volume. The nightly snapshot itself is untouched.
• Built images for the branch, once no other preview shares their layers.

The order is deliberate. DNS goes first, so no new request arrives halfway through. Secrets go before volumes, so a credential never outlives the thing it was protecting.

on_merge and on_close

preview:
  teardown: on_merge

on_merge is the default. The preview is removed when the pull request merges. If the pull request is closed without merging, the preview is removed after a one-hour grace period, in case it was closed by mistake. Reopening inside that hour cancels the teardown.

on_close removes the preview the moment the pull request closes for any reason, with no grace period. Teams with strict data-retention rules tend to choose it.

There is no "never." You can run canary down yourself at any time, but you cannot configure a preview to survive its pull request. If an environment needs to persist, it is not a preview, and it should not be billed or secured like one.

Waiting for running jobs

The one place where fast and correct pull against each other is background work. If the worker is halfway through a job when the merge lands, killing it can leave a half-written export, or a test webhook that never gets its second call.

So teardown asks first. The runner stops web first, then gives each worker up to 10 minutes to finish the jobs it has already picked up before it removes the container. Jobs still in the queue are dropped. Most previews have nothing running at merge time, which is why the median stays at 2m 12s. The slowest teardowns are the ones doing the right thing.

If a job does not finish inside the window, it is stopped, and the audit entry says so, with the job's name.

The audit trail

Every teardown writes one record: what triggered it, each resource removed with a timestamp, and the total. It reads like the build log in reverse.

14:03:07  pull_request.merged  #482 into main
14:03:08  dns removed          pr-482.northwind.canary.run
14:03:11  secrets revoked      3 keys
14:03:52  jobs drained         worker, 1 finished
14:04:40  volumes removed      postgres, redis
14:05:19  teardown complete    2m 12s

The record is kept after the preview is gone, in the workspace audit log on the Team and Enterprise plans. When a security reviewer asks where a copy of customer data went, the answer is a row with a time on it.

Why it belongs on the pricing page

Teardown is also what keeps per-hour pricing honest. A preview that is asleep costs nothing, as Theo describes in a preview nobody opens should cost nothing, and a preview that is gone can never wake up by accident. At Oxbow, which replaced two always-on staging clusters, teardown runs in 2m 05s, and nothing is left running at the end of the month.

Our home page says there is nothing to remember to delete. That sentence took more engineering than the build log did, and it is the reason the rest of the system stays simple. The plans and what each one keeps in the audit log are on the pricing page.